Add support for PostgreSQL's ORDER BY ... USING <operator> clause by LucaCappelletti94 · Pull Request #2246 · apache/datafusion-sqlparser-rs

LucaCappelletti94 · 2026-02-26T19:49:51Z

This PR adds parser and AST support for PostgreSQL USING operators in ORDER BY expressions, including:

top-level ORDER BY
aggregate argument list ORDER BY (e.g. inside aggfns(...) / string_agg(...) style clauses)

Problem

sqlparser-rs previously rejected valid PostgreSQL statements containing:

ORDER BY <expr> USING <operator>

with errors like:

Expected: ), found: using

This blocked parsing of several PostgreSQL regression-style aggregate statements.

Root Cause

parse_order_by_expr_inner only supported:

ASC | DESC
NULLS FIRST | NULLS LAST

and had no branch to parse USING <operator>.

Dialect Scope Decision

ORDER BY ... USING <operator> is intentionally enabled for PostgreSQL only.

Rationale:

PostgreSQL explicitly documents ORDER BY expression [ USING operator ] ... in SELECT.
Other dialects supported by this repository generally document ORDER BY with expression + ASC|DESC (+ null ordering), but not USING <operator>.

References:

Complete Examples

PostgreSQL: accepted

SELECT a FROM t ORDER BY a USING <;

SELECT a FROM t ORDER BY a USING OPERATOR(pg_catalog.<) NULLS LAST;

SELECT aggfns(DISTINCT a, a, c ORDER BY c USING ~<~, a)
FROM (VALUES (1,3,'foo'),(0,NULL,NULL),(2,2,'bar'),(3,1,'baz')) v(a,b,c),
     generate_series(1,2) i;

CREATE OR REPLACE VIEW agg_view1 AS
SELECT aggfns(a,b,c ORDER BY c USING ~<~)
FROM (VALUES (1,3,'foo'),(0,NULL,NULL),(2,2,'bar'),(3,1,'baz')) v(a,b,c);

PostgreSQL: rejected (invalid syntax)

SELECT a FROM t ORDER BY a USING ;
-- Error: Expected an ordering operator after USING

SELECT a FROM t ORDER BY a USING OPERATOR();
-- Error: Expected an operator name

SELECT a FROM t ORDER BY a USING < DESC;
-- Error: ASC/DESC cannot be used together with USING in ORDER BY

iffyio · 2026-03-02T11:58:16Z

src/parser/mod.rs

+        }
+    }
+
+    fn is_valid_order_by_using_operator_symbol(symbol: &str) -> bool {


is this code necessary?

Removed, parse_order_by_using_operator now uses dialect.is_custom_operator_part(...) directly. No separate symbol-check helper anymore. I wasn't aware there was a dialect helper method.

iffyio · 2026-03-02T11:59:01Z

src/parser/mod.rs


-        let options = self.parse_order_by_options()?;
+        let using_operator = if !with_operator_class
+            && dialect_of!(self is PostgreSqlDialect)


if we need to dialect guard this, I think we can introduce a dialect method instead of the macro

Added supports_order_by_using_operator() on Dialect (default false), enabled in PostgreSqlDialect, and parser now checks that method instead of dialect_of!. I double checked that no other dialect supports it at this time.

iffyio · 2026-03-02T12:00:08Z

src/parser/mod.rs

+                Token::Word(w)
+                    if w.quote_style.is_none() && terminal_keywords.contains(&w.keyword) =>
+                {
+                    break;


are these diffs required for this PR?

No, it was nightly clippy fixes. Removed from git history.

iffyio · 2026-03-02T12:01:23Z

tests/sqlparser_postgres.rs

+    );
+
+    // `USING` in ORDER BY is PostgreSQL-specific and should not parse in GenericDialect.
+    let generic = TestedDialects::new(vec![Box::new(GenericDialect {})]);


note, per the dialect comment, we'd want to avoid hardcoding dialects in tests

Replaced the GenericDialect negative case with a local wrapper dialect that behaves like Postgres but returns false for supports_order_by_using_operator().

LucaCappelletti94 · 2026-03-03T13:21:08Z

I’ve applied the requested changes and force-pushed the branch, so to remove irrelevant clippy changes from the commits.

Replaced the hardcoded parser guard (dialect_of!(...PostgreSqlDialect)) with a dialect capability method: Dialect::supports_order_by_using_operator(), enabled in PostgreSqlDialect only. I have also spent a bit of time checking yet again if any other dialects had it, but so far no other dialects support it.
Removed the dedicated is_valid_order_by_using_operator_symbol helper and now validate USING operators through existing dialect behavior (dialect.is_custom_operator_part(...)), so we don’t duplicate operator-character rules in parser code.
Trimmed the PR scope/history to a single focused commit and removed unrelated nightly clippy code smell fixes - I hadn't realized it was a nightly only rant.

iffyio · 2026-03-04T13:40:21Z

src/parser/mod.rs

+        let using_operator = if !with_operator_class
+            && self.dialect.supports_order_by_using_operator()
+            && self.parse_keyword(Keyword::USING)
+        {
+            Some(self.parse_order_by_using_operator()?)
+        } else {
+            None
+        };
+
+        let options = if using_operator.is_some() {
+            if self
+                .peek_one_of_keywords(&[Keyword::ASC, Keyword::DESC])
+                .is_some()
+            {
+                return parser_err!(
+                    "ASC/DESC cannot be used together with USING in ORDER BY".to_string(),
+                    self.peek_token_ref().span.start
+                );
+            }
+            OrderByOptions {
+                asc: None,
+                nulls_first: self.parse_order_by_nulls_first_last(),
+            }


would it be possible to use something like this representation instead?

pub enum OrderByExpr { Asc, Desc, Using(...), UsingOperator(...), } pub struct OrderByOptions { pub expr: Option<OrderByExpr>, pub nulls_first: Option<bool>, }

iffyio · 2026-03-04T13:42:13Z

tests/sqlparser_postgres.rs

+    #[derive(Debug)]
+    struct OrderByUsingDisabledDialect;
+
+    impl Dialect for OrderByUsingDisabledDialect {
+        fn is_identifier_start(&self, ch: char) -> bool {
+            PostgreSqlDialect {}.is_identifier_start(ch)
+        }
+
+        fn is_identifier_part(&self, ch: char) -> bool {
+            PostgreSqlDialect {}.is_identifier_part(ch)
+        }
+
+        fn supports_order_by_using_operator(&self) -> bool {
+            false
+        }
+    }
+
+    let without_order_by_using = TestedDialects::new(vec![Box::new(OrderByUsingDisabledDialect)]);
+    assert!(without_order_by_using
+        .parse_sql_statements("SELECT a FROM t ORDER BY a USING <;")


I think we can have the tests in common.rs instead to cover dialects via the all_dialects_where(|d| d.support*) pattern. Since the impl is guarded by the dialect method vs explicit to postgres

iffyio · 2026-03-04T13:43:04Z

src/ast/query.rs

 pub struct OrderByExpr {
    /// The expression to order by.
    pub expr: Expr,
+    /// Optional PostgreSQL `USING <operator>` clause.


can we include reference doc to maybe this?
https://www.postgresql.org/docs/current/sql-select.html

so folks know where to find this feature easily

fyi: re the comment would be nice to include the link

iffyio · 2026-03-20T12:45:02Z

src/parser/mod.rs

+            let operator = last_part.to_string();
+            if operator.is_empty()
+                || !operator
+                    .chars()
+                    .all(|ch| dialect.is_custom_operator_part(ch))
+            {
+                return self.expected_ref("an operator name", self.peek_token_ref());
+            }


the to_string() cloning doesn't seem to be required here? But in general this logic iiuc is validating some property of the allowed naming? if so I think it would make sense to skip the validation here in the parser (same for the similar logic below, so that if the code is to be kept then we likely want to pull it out to a reusable function)

iffyio · 2026-03-20T12:46:01Z

src/parser/mod.rs

+            if self
+                .peek_one_of_keywords(&[Keyword::ASC, Keyword::DESC])
+                .is_some()
+            {
+                return parser_err!(
+                    "ASC/DESC cannot be used together with USING in ORDER BY".to_string(),
+                    self.peek_token_ref().span.start
+                );
+            }
+            OrderByOptions {
+                asc: None,
+                nulls_first: self.parse_order_by_nulls_first_last(),


I think we can skip this validation

iffyio · 2026-03-20T12:50:24Z

src/parser/mod.rs

+        }
+    }
+
+    fn parse_order_by_nulls_first_last(&mut self) -> Option<bool> {


Suggested change

fn parse_order_by_nulls_first_last(&mut self) -> Option<bool> {

fn parse_null_ordering_modifier(&mut self) -> Option<bool> {

iffyio · 2026-03-20T12:51:31Z

src/ast/query.rs

 pub struct OrderByExpr {
    /// The expression to order by.
    pub expr: Expr,
+    /// Optional PostgreSQL `USING <operator>` clause.


fyi: re the comment would be nice to include the link

iffyio · 2026-03-20T12:52:35Z

tests/sqlparser_postgres.rs


+#[test]
+fn parse_pg_aggregate_order_by_using_operator() {
+    let sql = "SELECT aggfns(DISTINCT a, a, c ORDER BY c USING ~<~, a) FROM t";


can we move the tests to common and use the all_dialects_where helper method for the test cases?

LucaCappelletti94 marked this pull request as ready for review February 26, 2026 19:55

iffyio reviewed Mar 2, 2026

View reviewed changes

PostgreSQL: support ORDER BY USING via dialect capability

7c2e3b6

LucaCappelletti94 force-pushed the postgres-regression-2 branch from 3b2da72 to 7c2e3b6 Compare March 2, 2026 21:19

LucaCappelletti94 added 2 commits March 2, 2026 22:51

Merge branch 'main' into postgres-regression-2

ca32b8f

Merge branch 'main' into postgres-regression-2

e8056c7

iffyio reviewed Mar 4, 2026

View reviewed changes

iffyio reviewed Mar 20, 2026

View reviewed changes

	fn parse_order_by_nulls_first_last(&mut self) -> Option<bool> {
	fn parse_null_ordering_modifier(&mut self) -> Option<bool> {

Conversation

LucaCappelletti94 commented Feb 26, 2026

Problem

Root Cause

Dialect Scope Decision

Complete Examples

PostgreSQL: accepted

PostgreSQL: rejected (invalid syntax)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LucaCappelletti94 commented Mar 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants